package com.google.jessewilson.codesearch.api.spi;

import com.google.jessewilson.codesearch.api.CodeFile;
import com.google.jessewilson.codesearch.api.Line;
import com.google.jessewilson.codesearch.api.Page;
import com.google.jessewilson.codesearch.api.Query;
import com.google.jessewilson.codesearch.api.SearchProviderAware;
import com.google.jessewilson.codesearch.api.SearchProviderException;
import com.google.jessewilson.codesearch.api.SearchResult;
import com.google.jessewilson.codesearch.util.ProducerSink;

import java.io.File;

/**
 * A search provider can turn queries into results!
 *
 * @author jessewilson
 */
public interface SearchProviderBackend extends SearchProviderAware {

  /**
   * Searches for the query and returns results.
   *
   * @param sink the sink to output results to
   * @param page the results to include. It is an error to include
   *     results from a different page. Not including all the results
   *     from a page is acceptable, however.
   * @throws com.google.jessewilson.codesearch.api.SearchProviderException if the search could not be done for any
   *   reason
   */
  public SearchResult search(Query query, ProducerSink<Line> sink, Page page)
      throws SearchProviderException;

  /**
   * Copies the source file to the local filesystem.
   *
   * @param source the source file to copy
   * @param target the location to copy the source file to
   * @throws SearchProviderException if the file could not be copied for any
   *   reason
   */
  public void downloadFile(CodeFile source, File target)
      throws SearchProviderException;

}
